<?php

namespace PhpYes\Com;

/**
 * filename to absolute path interface
 * 名字不好取，想要完全表达意思，名字太长，
 * 缩短名字长度，有时又不能完全表达想要的意思，
 * 甚至可能让看到的人理解 成其它意思 或者 产生歧义.
 *
 * 有各种各样的文档讲解如何命名，但命名还是永远让人纠结，
 * 使用时，名字太长，用起来很难受，特别是在复杂表达式中，
 * 例如: application->render()->display(FilenameToAbsolutePath->absolutePath(Render::PAGE_ERROR));
 * 简化一下: app->render()->display(filemap->absp(Render::PAGE_ERROR));
 * 看起来一下子清爽不少
 *
 * 总之，取名难，这个接口也先定成这个名字，没有问题就先用着，如果遇到问题再改
 */
interface AbsoluteFilePathInterface
{

    /**
     * 获取 $filename 的绝对路径,
     * $filename 可以是 文件名, 文件别名, 文件昵称 等，具体表示 由实现决定,
     * 本质是一个映射(map)，从 $filename 到 绝对路径 的映射，$filename 是什么，完全由实现决定
     *
     * 接口由来:
     * Render.
     * displayError : 需要渲染一个 error 页面
     * display5xx : 需要渲染一个 5xx 页面
     * display4xx : 需要渲染一个 4xx 页面
     * display404 : 需要渲染一个 404 页面
     * 以前这几个函数都在应用层，需要渲染的页面直接写在函数实现里，
     * 然而应用层的不同地方(例如管理后台和前端网页) 或者 使用这个库的不同应用，
     * 都需要写这几个函数，这些函数除了页面不同，逻辑几乎完全相同，
     * 为了不再写这些重复的代码，就将这几个函数提取到了 Render 中来，
     *
     * 但是 应用层的不同地方 或者 使用这个库的不同应用 需要渲染的页面是不同的，
     * 这就需要应用向 Render 注入信息，
     * 有 3 种方法可以让 应用 向 Render 注入信息: 配置，虚函数，接口
     * 配置: 实例化 Render 时传入配置，配置就被保存在实例中，无论用不用这些配置，配置都要占用内存空间
     * 虚函数: 虚函数就意味着继承，即每次要注入不同信息时就需要一个子类来实现虚函数，操作起来有些麻烦
     * 接口: 接口可以说是最灵活的注入信息的方式了，用户可以使用继承，也可以不使用继承，只要实现了接口就行
     * 于是，我们选择了接口
     *
     * 那么接下来的问题就是我们需要定义哪些接口函数
     * 如果我们需要 1个页面就定义 1个接口函数, 例如: getErrorPage, get5xxPage, get4xxPage, get404Page
     * 从长远考虑，这样做不可取，因为如果以后我们还需要 其它的页面，那么我们就要定义其它的接口函数，
     * 所以 从长远考虑 定义 1 个不限定 特定页面 的 接口函数更加可取一些(就叫 取绝对路径函数)
     * 从当下考虑，我们又确实需要 几个特定页面，如果 取绝对路径函数 没有实现 当下我们需要的几个特定页面，
     * 那么 取绝对路径函数 对于当下 Render 的需求来说就毫无意义，
     * 感觉无论是立足长远，还是着眼于当下，无论怎么选择都不够完美，每次 review 时都让人纠结，
     * 最后决定直接搞 2 套，每个都得到满足，
     * AbsoluteFilePathInterface: 立足长远, 定义 1 个不限定 特定页面 的 可以扩展的 获取 $filename 的绝对路径 的接口函数
     * RenderDependsInterface: 着眼于当下，专为满足 Render 当下的需求，RenderDependsInterface 的实现可以基于 AbsoluteFilePathInterface 的实现 来实现
     *
     * @param string $filename - 文件名, 文件别名, 文件昵称 等都可以，具体表示 由实现决定
     * @return string - $filename 的绝对路径
     */
    public function absolutePath($filename);
}